home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / STK100.ZIP / DWS.BI next >
Text File  |  1995-02-17  |  10KB  |  253 lines
  1. '******************************************************************************
  2. 'File:      dws.bi
  3. 'Version:   1.0
  4. 'Tab stops: every 2 collumns
  5. 'Project:   The Sound ToolKit
  6. 'Copyright: 1994 DiamondWare, Ltd.  All rights reserved.
  7. 'Written:   by Erik Lorenzen, Keith Weiner, and Don Lemons
  8. 'Purpose:   Contains declarations for the DW Sound ToolKit
  9. 'History:   DL 08/24/94 Started translation
  10. '           KW 08/30/94 Modified
  11. '           DL 11/12/94 Re-Translated
  12. '           EL 11/26/94 Edited for clarity and funtionality
  13. '           EL 11/27/94 Finalized for v1.0
  14. '******************************************************************************
  15.  
  16.  
  17.  
  18. '******************************************************************************
  19. ' The following is the complete list of possible values for dwsErrNo.
  20. ' dwsErrNo may be set by any dws function.  Check its value whenever
  21. ' the return value of a dws function is 0 (error).
  22.  
  23. CONST dwsEZERO                                                    =  0
  24.  
  25. ' The following 3 errors may be triggered by any dws function
  26. CONST dwsNOTINITTED                                         =  1
  27. CONST dwsALREADYINITTED                                 =  2
  28. CONST dwsNOTSUPPORTED                                     =  3
  29.  
  30. 'The following 4 errors may be triggered by dwsDetectHardWare
  31. CONST dwsDetectHardwareUNSTABLESYSTEM     =  4
  32. CONST dwsDetectHardwareBADBASEPORT            =  5
  33. CONST dwsDetectHardwareBADDMA                     =  6
  34. CONST dwsDetectHardwareBADIRQ                     =  7
  35.  
  36. 'The following error may be triggered by dwsKill
  37. CONST dwsKillCANTUNHOOKISR                            =  8
  38.  
  39. 'The following error may be triggered by any dwsX (mixer) function
  40. CONST dwsXBADINPUT                                            =  9
  41.  
  42. 'The following 3 errors may be triggered by any dwsD (dig) function
  43. CONST dwsDNOTADWD                                             =  10
  44. CONST dwsDNOTSUPPORTEDVER                             =  11
  45. CONST dwsDINTERNALERROR                                 =  12
  46.  
  47. 'The following error may be triggered by dwsDPlay
  48. CONST dwsDPlayNOSPACEFORSOUND                     =  13
  49.  
  50. 'The following 2 errors may be triggered by dwsDSetRate
  51. CONST dwsDSetRateFREQTOLOW                            =  14
  52. CONST dwsDSetRateFREQTOHIGH                         =  15
  53.  
  54. 'The following 3 errors may be triggered by dwsMPlay
  55. CONST dwsMPlayNOTADWM                                     =  16
  56. CONST dwsMPlayNOTSUPPORTEDVER                     =  17
  57. CONST dwsMPlayINTERNALERROR                         =  18
  58. '------------------------------------------------------------------------------
  59.  
  60.  
  61. 'The follwing section defines bitfields which are used by various
  62. 'dws functions.  Each bit in a bitfield, by definition, may be
  63. 'set/reset independantly of all other bits.
  64.  
  65. 'The following 2 consts indicate the capabilities of the user's hardware
  66. CONST dwscapabilityFM                                     =  1
  67. CONST dwscapabilityDIG                                    =  2
  68.  
  69. 'The following 2 consts indicate the status of specified digital sounds
  70. CONST dwsDSOUNDSTATUSPLAYING                        =  1
  71. CONST dwsDSOUNDSTATUSSEQUENCED                    =  2
  72.  
  73. 'The following 2 consts indicate the status of music playback
  74. CONST dwsMSONGSTATUSPLAYING                         =  1
  75. CONST dwsMSONGSTATUSPAUSED                            =  2
  76. '******************************************************************************
  77.  
  78.  
  79.  
  80. 'The following section TYPEs the structs used by the STK.  In each
  81. 'case, the user must create an instance of the struct prior to making
  82. 'a call to an STK function which takes a pointer to it.  The STK does
  83. 'not keep a pointer to any of these structs internally; after the call
  84. 'returns, you may deallocate it, if you wish.
  85.  
  86.  
  87. 'NB: The STK _does_ keep pointers to songs and digitized sound buffers!
  88. 'dwsDetectHardWare can be told _not_ to autodetect particular values
  89. 'about the installed hardware.  This is useful if detecting DMA channel,
  90. 'for example, consistently causes a machine lockup.  To override the
  91. 'autodetect for a setting (causing the STK to accept it on faith),
  92. 'set the corresponding field in this struct to the correct value.
  93. 'Otherwise, set the field to ffff hex.  Since the autodetect is reliable,
  94. 'this is the recommended course of action, except in cases of known
  95. 'problems.
  96. TYPE dwsDETECTOVERRIDES
  97.     baseport     AS INTEGER          'base address of sound card (often 220 hex)
  98.  
  99.     digdma         AS INTEGER          'DMA channel
  100.     digirq         AS INTEGER          'IRQ level
  101.  
  102.     reserved     AS STRING * 10  'reserved
  103.  
  104. END TYPE
  105.  
  106.  
  107. 'A pointer to this struct is passed to dwsDetectHardWare, which fills
  108. 'it in.  It is then passed unmodified to dwsInit.  If you plan on
  109. 'writing this struct out to a file, it's important that you write
  110. 'the entire contents.  There is information (for internal STK use only)
  111. 'in the reserved[] field!
  112. TYPE dwsDETECTRESULTS
  113.     baseport     AS INTEGER          'base address of sound card (often 220 hex)
  114.  
  115.     capability AS INTEGER          'see CONSTs, above
  116.  
  117.     'The following 3 fields are only valid if FM music is supported
  118.     mustyp         AS INTEGER          '0=none, 1=OPL2
  119.     musnchan     AS INTEGER          '1=mono
  120.     musnvoice  AS INTEGER          'number of voices supported by hardware (11 for FM)
  121.  
  122.     'The following 4 fields are only valid if digitized sound is supported
  123.     dignbits     AS INTEGER          '0=none, 8=8 bit
  124.     dignchan     AS INTEGER          '1=mono
  125.     digdma         AS INTEGER          'DMA channel
  126.     digirq         AS INTEGER          'IRQ level
  127.  
  128.     mixtyp         AS INTEGER          '1=software, 2+ is hardware
  129.  
  130.     reserved     AS STRING * 44  'there are important values in here...
  131.  
  132. END TYPE
  133.  
  134.  
  135. 'A pointer to this struct is passed as a parameter to dws_Init.  This
  136. 'allows the user to tell the STK to use less than the full capabilities
  137. 'of the installed sound hardware, and/or the user's sound board
  138. 'may not support every feature of the STK.
  139. TYPE dwsIDEAL
  140.     musictyp     AS INTEGER          '0=No Music, 1=OPL2
  141.  
  142.     digtyp         AS INTEGER          '0=No Dig, 8=8bit
  143.     digrate      AS INTEGER          'sampling rate, in Hz
  144.     dignvoices AS INTEGER          'number of voices (up to 16)
  145.     dignchan     AS INTEGER          '1=mono
  146.  
  147.     reserved     AS STRING * 6
  148.  
  149. END TYPE
  150.  
  151.  
  152. 'A pointer to this struct is passed to dwsDPlay.
  153. 'Note that the soundnum field is filled in by dws_DPlay as a return value.
  154. TYPE dwsDPLAY
  155.     snd              AS LONG                 'pointer to buffer which holds a .DWD file
  156.     count          AS INTEGER          'number of times to play, or 0=infinite loop
  157.     priority     AS INTEGER          'higher numbers mean higher priority
  158.     presnd         AS INTEGER          'soundnum to sequence sound _after_
  159.     soundnum     AS INTEGER          'dws_DPlay returns a snd number from 10-65535
  160.  
  161.     reserved     AS STRING * 20
  162.  
  163. END TYPE
  164.  
  165.  
  166. 'A pointer to this struct is passed to dwsMPlay.
  167. TYPE dwsMPLAY
  168.     track          AS LONG                 'pointer to buffer which holds a .DWM file
  169.     count          AS INTEGER          'number of times to play, or 0=infinite loop
  170.  
  171.     reserved     AS STRING * 10
  172.  
  173. END TYPE
  174. '******************************************************************************
  175.  
  176.  
  177. '******************************************************************************
  178.  
  179. 'This function is callable at any time.  It returns the number of the
  180. 'last error which occured.
  181. DECLARE FUNCTION dwsErrNo%                     ALIAS "DWS_ERRNO"                    ()
  182. '------------------------------------------------------------------------------
  183.  
  184.  
  185. 'This subroutine is called at the end of the timer ISR (interrupt service
  186. 'routine).  If you're using the optional DWT (DW Timer), this happens
  187. 'automagically.  If you wrote your own timer handler routine, you must
  188. 'call this function regularly.
  189. DECLARE SUB          dwsUpdate                     ALIAS "DWS_UPDATE"                 ()
  190. '------------------------------------------------------------------------------
  191.  
  192.  
  193. 'The following functions have boolean return values.  A return of 0 (false)
  194. 'indicates an error.  If this occurs, check dwsErrNo for more info.
  195. DECLARE FUNCTION dwsDetectHardWare%  ALIAS "DWS_DETECTHARDWARE" (SEG dov AS dwsDetectOverrides, SEG dres AS dwsDetectResults)
  196.  
  197. DECLARE FUNCTION dwsInit%                      ALIAS "DWS_INIT"                     (SEG dres AS dwsDetectResults, SEG idl AS dwsIdeal)
  198.  
  199.  
  200. 'If the program has called dws_Init, it _MUST_ call dws_Kill before it
  201. 'terminates.
  202. '
  203. 'NB: Trap critical errors.  Don't let DOS put up the
  204. '    "Abort, Retry, Fail?" text.  ('sides, it'll destroy your pretty gfx)
  205. DECLARE FUNCTION dwsKill%                      ALIAS "DWS_KILL"                     ()
  206.  
  207.  
  208. 'The following 3 functions comprise the mixer section of the STK.  A
  209. 'value of 0 turns a channel off; a value of 255 is the loudest.
  210. DECLARE FUNCTION dwsXMaster%                 ALIAS "DWS_XMASTER"                (BYVAL volume%)
  211.  
  212. DECLARE FUNCTION dwsXMusic%                  ALIAS "DWS_XMUSIC"                 (BYVAL volume%)
  213.  
  214. DECLARE FUNCTION dwsXDig%                      ALIAS "DWS_XDIG"                     (BYVAL volume%)
  215.  
  216.  
  217. 'The following 10 functions comprise the digitized sound functions of
  218. 'the STK.  See the documentation for complete details.
  219. DECLARE FUNCTION dwsDPlay%                     ALIAS "DWS_DPLAY"                    (SEG dply AS dwsDPlay)
  220.  
  221. DECLARE FUNCTION dwsDSoundStatus%      ALIAS "DWS_DSOUNDSTATUS"     (BYVAL soundnumber%, SEG result%)
  222.  
  223. DECLARE FUNCTION dwsDSetRate%              ALIAS "DWS_DSETRATE"             (BYVAL frequency%)
  224.  
  225. DECLARE FUNCTION dwsDGetRate%              ALIAS "DWS_DGETRATE"             (SEG result%)
  226.  
  227. 'This function is callable at any time.
  228. DECLARE FUNCTION dwsDGetRateFromDWD% ALIAS "DWS_DGETRATEFROMDWD"(BYVAL pointer&, SEG result%)
  229.  
  230. DECLARE FUNCTION dwsDDiscard%              ALIAS "DWS_DDISCARD"             (BYVAL soundnum%)
  231.  
  232. DECLARE FUNCTION dwsDDiscardAO%          ALIAS "DWS_DDISCARDAO"         (BYVAL pointer&)
  233.  
  234. DECLARE FUNCTION dwsDClear%                  ALIAS "DWS_DCLEAR"                 () 'Affects all sounds
  235.  
  236. DECLARE FUNCTION dwsDPause%                  ALIAS "DWS_DPAUSE"                 () 'Affects all sounds
  237.  
  238. DECLARE FUNCTION dwsDUnPause%              ALIAS "DWS_DUNPAUSE"             () 'Affects all sounds
  239.  
  240.  
  241. 'The following 5 functions comprise the music functions of the STK.
  242. 'See the documentation for complete details.
  243. DECLARE FUNCTION dwsMPlay%                     ALIAS "DWS_MPLAY"                    (SEG mply AS dwsMPlay)
  244.  
  245. DECLARE FUNCTION dwsMSongStatus%         ALIAS "DWS_MSONGSTATUS"        (SEG result%)
  246.  
  247. DECLARE FUNCTION dwsMClear%                  ALIAS "DWS_MCLEAR"                 ()
  248.  
  249. DECLARE FUNCTION dwsMPause%                  ALIAS "DWS_MPAUSE"                 ()
  250.  
  251. DECLARE FUNCTION dwsMUnPause%              ALIAS "DWS_MUNPAUSE"             ()
  252. '******************************************************************************
  253.